⚠️ GitHub issue #48623 has been automatically assigned in GitHub to PR creator.

From #48623 (comment)

It looks as though all the headers can (and should) be populated in the ReportUtils.send_email method.

Could you explain the reason? If we use the approach, it's (a bit) difficult to implement dry-run. (We need to pass more arguments to ReportUtils.send_email.)

At present, the headers have to be generated in lots of places, which means more maintenance and more testing.

As to doing a dry-run, that depends on whether you need to see all the headers or just the body.

The Python email library builds up the message for sending, and you can just print the message instead of sending it.

AFAICT when you refer to dry-run, you mean using something like output.write(email_report.render("workflow_report"))

If the templates no longer contain the headers, then of course they won't be shown.

I think the simplest way round this is to add a includeHeadersparameter to JinjaReport.render, with default False. If True, the response should include the relevant header values.

The dry-run code would then need to be changed to

output.write(email_report.render("workflow_report"), True)

Thanks. I understand your point. We should provide a function for general headers generation, right?

How about the 6b31c32 approach? EmailReport.render(template_name, headers) generates email.message.EmailMessage. It also fills the default header values such as Message-Id.

How about the 6b31c32 approach?

This does not solve the issue that mail headers need special handling, and still leaves multiple locations to be maintained and tested.

This does not solve the issue that mail headers need special handling

What does the "special handing" mean? I thought that it's non ASCII characters encoding, folding a long line and so on. And I thought that all of them are processed by the email.message.EmailMessage.[] automatically.

and still leaves multiple locations to be maintained and tested.

What does the "multiple locations" mean? We should not have header related information in dev/archery/archery/ci/cli.py and dev/archery/archery/crossbow/cli.py, right?

What does the "special handing" mean?

I see that most of the header values are passed to EmailMessage[]
However, the code makes assumptions about the syntax of the From header.
You need to use https://docs.python.org/3/library/email.headerregistry.html#email.headerregistry.Address
It would be safer to do the same for the To: address as well.

Also I see that the tests don't account for sender_name.

What does the "multiple locations" mean?

That the same code appears in multiple locations.

By which I mean that the code transforms the data.
It would be better to pass just the raw values in the data, and have the render method do all the formatting etc.
This means dropping the Date header and leaving it for the render method to construct.

I didn't know email.headerregistry.Address. Thanks. I've changed to use it.

I reconstructed EmailReport API. Now, we always need to define subclass of EmailReport to generate headers in EmailReport.

I confirmed archery ci report manually:

$ archery ci report-email --dry-run --sender-email arrow@commit-email.info --sender-name Arrow --recipient-email kou@clear-code.com 20867714288
MIME-Version: 1.0
Message-Id: <176802522672.3361134.1173117024017522311@coolian>
Date: Fri, 09 Jan 2026 22:42:43 -0000
From: Arrow <arrow@commit-email.info>
To: kou@clear-code.com
Subject: [2026-01-09] Arrow Build Report for Job R Extra: 0 failed
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit

Arrow Build Report for R Extra

Workflow URL: https://github.com/apache/arrow/actions/runs/20867714288

@raulcd Do you want to review this before we merge this?